extends layout

append style
  link(rel="stylesheet", href="/docs/css/inlinecpc.css")
  script(type="text/javascript" src="/docs/js/native.js")

block content
  :markdown
    ## Documents

    <script>
      _native.init("CK7DT53U",{
        targetClass: 'native-inline'
      });
    </script>

    <div class="native-inline">
      <a href="#native_link#"><span class="sponsor">Sponsor</span> #native_company# — #native_desc#</a>
    </div>

    Mongoose [documents](./api.html#document-js) represent a one-to-one mapping
    to documents as stored in MongoDB. Each document is an instance of its
    [Model](./models.html).

    ### Retrieving

    There are many ways to retrieve documents from MongoDB. We won't cover that
    in this section. See the chapter on [querying](./queries.html) for detail.

    ### Updating

    There are a number of ways to update documents. We'll first look at a
    traditional approach using [findById](./api.html#model_Model.findById):

    ```javascript
    Tank.findById(id, function (err, tank) {
      if (err) return handleError(err);

      tank.size = 'large';
      tank.save(function (err, updatedTank) {
        if (err) return handleError(err);
        res.send(updatedTank);
      });
    });
    ```

    You can also use [`.set()`](./api.html#document_Document-set)
    to modify documents. Under the hood, `tank.size = 'large';` becomes
    `tank.set({ size: 'large' })`.

    ```javascript
    Tank.findById(id, function (err, tank) {
      if (err) return handleError(err);

      tank.set({ size: 'large' });
      tank.save(function (err, updatedTank) {
        if (err) return handleError(err);
        res.send(updatedTank);
      });
    });
    ```

    This approach involves first retrieving the document from Mongo, then
    issuing an update command (triggered by calling `save`). However, if we
    don't need the document returned in our application and merely want to
    update a property in the database directly,
    [Model#update](./api.html#model_Model.update) is right for us:

    ```javascript
    Tank.update({ _id: id }, { $set: { size: 'large' }}, callback);
    ```

    If we do need the document returned in our application there is another,
    often [better](./api.html#model_Model.findByIdAndUpdate), option:

    ```javascript
    Tank.findByIdAndUpdate(id, { $set: { size: 'large' }}, { new: true }, function (err, tank) {
      if (err) return handleError(err);
      res.send(tank);
    });
    ```

    The `findAndUpdate/Remove` static methods all make a change to at most one
    document, and return it with just one call to the database. There
    [are](./api.html#model_Model.findByIdAndRemove)
    [several](./api.html#model_Model.findOneAndUpdate)
    [variations](./api.html#model_Model.findOneAndRemove) on the
    [findAndModify](http://www.mongodb.org/display/DOCS/findAndModify+Command)
    theme. Read the [API](./api.html) docs for more detail.

    _Note that `findAndUpdate/Remove` do *not* execute any hooks or validation before making the change in the database. You can use the [`runValidators` option](/docs/validation.html#update-validators) to access a limited subset of document validation. However, if you need hooks and full document validation, first query for the document and then `save()` it._

    ### Validating

    Documents are validated before they are saved. Read the
    [api](./api.html#document_Document-validate) docs or the
    [validation](./validation.html) chapter for detail.

    ### Overwriting

    You can overwrite an entire document using `.set()`. This is handy if you
    want to change what document is being saved in [middleware](./middleware.html).

    ```javascript
    Tank.findById(id, function (err, tank) {
      if (err) return handleError(err);
      // Now `otherTank` is a copy of `tank`
      otherTank.set(tank);
    });
    ```

    ### Next Up

    Now that we've covered Documents, let's take a look at
    [Subdocuments](/docs/subdocs.html).
